<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
    "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta name="generator" content="AsciiDoc 8.2.7" />
<style type="text/css">
body {
	font-family:'Times new roman', serif;
	max-width:52.666em;
}

div#header {
	text-align: center;
}

h1,h2,h3,h4,h5 {
	font-family:'Times new roman', serif;
	font-weight: normal;
}

h1 {
	font-size:40px;
	margin-bottom: 150px;
}

div#toc {
	text-align: left;
}

h2, div#toctitle {
	font-size:28.3px;
	line-height:1.413;
	margin-top: 100px;
}

div#toctitle {
	margin-bottom: 40px;
}

h3 {
	font-size:20px;
	line-height:1;
	margin-top: 25px;
}

h4 {
	font-size:15px;
	line-height:1.5;
}

p, dl {
	margin-left: 20px;
	text-align: justify;
	line-height: 1.3em;
}

dl dt {
	font-style: italic;
}
dl dd p {
	margin-top: 0px;
}

pre {
	margin-left: 40px;
	padding-left: 5px;
}
pre, tt {
	font-family: "Courier New", courier, monospace;
	color: #202020;
}

ul {
	margin-left: 20px;
}

div.toclevel1 {
	margin-left: 20px;
}

div.toclevel2 {
	margin-left: 40px;
}

div.toclevel3 {
	margin-left: 60px;
}

div.toclevel4 {
	margin-left: 80px;
}

div.admonitionblock div.title {
	font-weight: bold;
	margin-right: 20px;
}
div.tableblock {
	margin-left: 30px;
}
div.imageblock {
	margin-left: 30px;
}
div.image-title {
	font-style: italic;
	font-size: small;
}

/* vim: set ft=css ts=4 sw=4 noexpandtab: */


</style>
<script type="text/javascript">
/*<![CDATA[*/
window.onload = function(){generateToc(3)}
/* Author: Mihai Bazon, September 2002
 * http://students.infoiasi.ro/~mishoo
 *
 * Table Of Content generator
 * Version: 0.4
 *
 * Feel free to use this script under the terms of the GNU General Public
 * License, as long as you do not remove or alter this notice.
 */

 /* modified by Troy D. Hanson, September 2006. License: GPL */
 /* modified by Stuart Rackham, October 2006. License: GPL */

function getText(el) {
  var text = "";
  for (var i = el.firstChild; i != null; i = i.nextSibling) {
    if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
      text += i.data;
    else if (i.firstChild != null)
      text += getText(i);
  }
  return text;
}

function TocEntry(el, text, toclevel) {
  this.element = el;
  this.text = text;
  this.toclevel = toclevel;
}

function tocEntries(el, toclevels) {
  var result = new Array;
  var re = new RegExp('[hH]([2-'+(toclevels+1)+'])');
  // Function that scans the DOM tree for header elements (the DOM2
  // nodeIterator API would be a better technique but not supported by all
  // browsers).
  var iterate = function (el) {
    for (var i = el.firstChild; i != null; i = i.nextSibling) {
      if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
        var mo = re.exec(i.tagName)
        if (mo)
          result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
        iterate(i);
      }
    }
  }
  iterate(el);
  return result;
}

// This function does the work. toclevels = 1..4.
function generateToc(toclevels) {
  var toc = document.getElementById("toc");
  var entries = tocEntries(document.getElementsByTagName("body")[0], toclevels);
  for (var i = 0; i < entries.length; ++i) {
    var entry = entries[i];
    if (entry.element.id == "")
      entry.element.id = "toc" + i;
    var a = document.createElement("a");
    a.href = "#" + entry.element.id;
    a.appendChild(document.createTextNode(entry.text));
    var div = document.createElement("div");
    div.appendChild(a);
    div.className = "toclevel" + entry.toclevel;
    toc.appendChild(div);
  }
  if (entries.length == 0)
    document.getElementById("header").removeChild(toc);
}
/*]]>*/
</script>
<title>Templum Userguide</title>
</head>
<body>
<div id="header">
<h1>Templum Userguide</h1>
<span id="author">Ferry Boender</span><br />
<span id="revision">version 0.4.0,</span>
Oct 8, 2009
<div id="toc">
  <div id="toctitle">Table of Contents</div>
  <noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>
</div>
</div>
<h2 id="_about">1. About</h2>
<div class="sectionbody">
<div class="para"><p>Templum is an extremely lightweight, simple yet powerful and fast templating
engine for PHP. It re-uses the power of PHP itself for rendering templates, but
provides additional features making it easier to write templating code.
Rendering templates using Templum is very fast; it approximates native PHP
rendering speed for include() statements.</p></div>
<h3 id="_features">1.1. Features</h3><div style="clear:left"></div>
<div class="ilist"><ul>
<li>
<p>
Lightweight. About 140 lines of code (excluding +/- 140 lines of API comments).
</p>
</li>
<li>
<p>
Re-uses PHP alternative syntax for clarity and full power.
</p>
</li>
<li>
<p>
Very fast. Renders 10,000 templates in 0.741s (Native PHP takes
  0.633s).
</p>
</li>
<li>
<p>
I18N (translated) templates.
</p>
</li>
<li>
<p>
Per-session caching of rendered templates.
</p>
</li>
<li>
<p>
Inheritance.
</p>
</li>
<li>
<p>
Security by automatic encoding of HTML entities.
</p>
</li>
<li>
<p>
Universal, global and local variables.
</p>
</li>
<li>
<p>
PHP v4 and v5 support.
</p>
</li>
</ul></div>
</div>
<h2 id="_usage">2. Usage</h2>
<div class="sectionbody">
<h3 id="_api">2.1. API</h3><div style="clear:left"></div>
<div class="para"><p>Templum consists of two main classes.</p></div>
<div class="vlist"><dl>
<dt>
<tt><a href="http://templum.electricmonk.nl/docs/api/html/classTemplum.html">Templum</a></tt>
</dt>
<dd>
<p>
  The Templum class is the main class that facilitates templates. It retrieves
  (translated) templates from disk or cache, compiles them and then returns
  them ready for rendering as a TemplumTemplate class instance.
</p>
</dd>
<dt>
<tt><a href="http://templum.electricmonk.nl/docs/api/html/classTemplumTemplate.html">TemplumTemplate</a></tt>
</dt>
<dd>
<p>
  TemplumTemplate class instances represent templates ready for rendering by
  your application. They are instantiated by the Templum class, so you
  shouldn't have to create them yourself. They handle the actual rendering of
  the template. The TemplumTemplate class also knows how to handle errors in
  your templates, and has helper functions which can be used from your
  templates to easily include other templates and to render variabels.
</p>
</dd>
</dl></div>
<div class="para"><p>For a complete overview of the API, please see the
<a href="http://templum.electricmonk.nl/docs/api/html/index.html">API reference
documentation</a>.</p></div>
<div class="para"><p>Here's an example that uses just about all of the Templum API, except for
Internationalisation:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>&lt;?php

require_once('templum.php');

// Configuration.
$pathTemplates = 'view';    // Path where templates live.
$appTitle = 'Hello World';  // Application title.
$author = 'Ferry Boender';  // Application author.
$username = 'jjohnson';     // Currently logged in user (normally from session).

// Create the Templum template engine. The templates live in the 'view'
// directory. We pass one universal variable: the application title.
$templum = new Templum($pathTemplates, compact('appTitle'));

// Turn off automatic escaping of {{ }} contents using htmlspecialchars().
$templum-&gt;setAutoEscape(False);

// Set another universal variable.
$templum-&gt;setVar('author', $author);

// Retrieve the template with path 'view/account/list.tpl'. We pass the
// $username as a global variable to the template and turn on automatic
// escaping for this template.
$tpl = $templum-&gt;template('account/list', compact('username'), True);

// Set another global variable.
$templum-&gt;setVar('username', $username);

// Define some data. This would normally come from a database or something.
$accounts = array(
   array('id'=&gt;1, 'username'=&gt;'jjohnson',  'realname'=&gt;'John Johnson'),
   array('id'=&gt;2, 'username'=&gt;'ppeterson', 'realname'=&gt;'Pete Peterson'),
   array('id'=&gt;3, 'username'=&gt;'jdoe',      'realname'=&gt;'John Doe'),
);

// Render the template with the accounts data.
$output = $tpl-&gt;render(compact('accounts'));

print($output);
?&gt;</tt></pre>
</div></div>
<h3 id="_template_language">2.2. Template Language</h3><div style="clear:left"></div>
<div class="para"><p>The Templum template language is extremely simple. It re-uses PHP's own
<a href="http://nl2.php.net/alternative_syntax">alternative syntax</a> for control
logic in the templates. It includes some simple special markup that makes it
easier to write templates:</p></div>
<div class="vlist"><dl>
<dt>
<tt>{{</tt> and <tt>}}</tt>
</dt>
<dd>
<p>
        Echo's the variable, function or other PHP printables between the
        accolades. Echo'ed contents is automatically escaped using
        <tt>htmlspecialchars()</tt> (can be turned off).
</p>
</dd>
<dt>
<tt>[[</tt> and <tt>]]</tt>
</dt>
<dd>
<p>
        Execute the PHP code between the brackets.
</p>
</dd>
<dt>
<tt>@line</tt>
</dt>
<dd>
<p>
        An <tt>at</tt> sign (@) at the beginning of the line (prepended whitespace is
        allowed) will cause the entire line to be executed as PHP code.
</p>
</dd>
</dl></div>
<div class="para"><p>It is recommended to use the Alternative PHP syntax for control structures
(<tt>if</tt>, <tt>while</tt>, <tt>for</tt>, etc) as it greatly enhances the readability of your
templates.</p></div>
<div class="para"><p>An example of a template that uses all available syntax as well as the
Alternative PHP syntax:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>[[
if (!function_exists('helperBtnAction')) {
   function helperBtnAction($action, $id, $icon) {
      echo('&lt;a href="?action='.$action.'&amp;id='.$id.'"&gt;');
      echo('&lt;img src="ico/'.$icon.'.png" alt="'.$icon.'" border="0" /&gt;');
      echo('&lt;/a&gt;');
   };
};
]]
&lt;h1&gt;User list&lt;/h1&gt;

&lt;p&gt;Hello {{$username}}, here's a list of all the users:&lt;/p&gt;

&lt;div id="accounts"&gt;
   @if (count($accounts) &lt;= 0):
      No accounts found.
   @else:
      &lt;table&gt;
         &lt;tr&gt;
            &lt;th&gt;&amp;nbsp;&lt;/th&gt;
            &lt;th&gt;Username&lt;/th&gt;
            &lt;th&gt;Full naam&lt;/th&gt;
         &lt;/tr&gt;
         @foreach ($accounts as $account):
            &lt;tr&gt;
               &lt;td&gt;[[helperBtnAction('account.edit', $account['id'], 'edit')]]&lt;/td&gt;
               &lt;td&gt;{{$account['username']}}&lt;/td&gt;
               &lt;td&gt;{{$account['realname']}}&lt;/td&gt;
            &lt;/tr&gt;
         @endforeach
         &lt;tr&gt;
            &lt;td&gt;[[helperBtnAction('account.add', '', 'add')]]&lt;/td&gt;
            &lt;td colspan="4"&gt;&amp;nbsp;&lt;/td&gt;
         &lt;/tr&gt;
      &lt;/table&gt;
   @endif
&lt;/div&gt;</tt></pre>
</div></div>
<h3 id="_variables">2.3. Variables</h3><div style="clear:left"></div>
<div class="para"><p>Variables can be easily used in your templates. Templum provides three types
of variables:</p></div>
<div class="ilist"><ul>
<li>
<p>
Universal Variables
</p>
</li>
<li>
<p>
Global Variables
</p>
</li>
<li>
<p>
Local Variables
</p>
</li>
</ul></div>
<div class="para"><p>Each of these are explained in the sections below. Templum can generally take variables straight away by passing a paramter containing an array when invoking one of its methods. For instance, we can pass local variables to a template when rendering it:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>$username = "jjohnson";
$realname = "John Johnson";

print($tpl-&gt;render(array('username' =&gt; $username, 'realname' =&gt; $realname));</tt></pre>
</div></div>
<div class="para"><p>A more convenient way of passing these variables where you do not need to build an entire array each time is the <tt>compact()</tt> PHP construct. <tt>compact()</tt> takes string parameters and constructs an associative array for you on the fly. It does so by interpreting the strings you pass as variables from the local scope. Thus the above example can be rewritten as:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>$username = "jjohnson";
$realname = "John Johnson";

print($tpl-&gt;render(compact('username', 'realname'));</tt></pre>
</div></div>
<h4 id="_universal_variables">2.3.1. Universal Variables:</h4>
<div class="para"><p>Universal variables are variables which will be made available to all the
templates you retrieve via a single Templum instance. They are mostly useful
for variables which need to be available in your entire application, such as
the name of the current user, the application's title, the currently active
controller, etc. Naturally you can also assign a helper class which can render
common elements of your User Interface to a universal variable and use that
from your templates.</p></div>
<div class="para"><p>Universal variables are set in the constructor of the main Templum template
engine class, or at a later stage using the <tt>setVar()</tt> method on the Templum
instance. All templates you retrieve via this Templum instance will have the
variables set.</p></div>
<div class="para"><p>An example:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>&lt;?php

require_once('templum.php');

// Define some universal variables
$appTitle = 'My First App';
$username = 'fboender';
$uiElements = new UIElements(); // Helper class

// Create the Templum instance and the universal $appTitle variable.
$templum = new Templum('view', compact('appTitle'));
// Add some more universal variables.
$templum-&gt;setVar('username', $username);
$templum-&gt;setVar('uiElements', $uiElements);

// Retrieve three templates. $username, $appTitle and $uiElements will be
// available in all three templates.
$tmplHeader = $templum-&gt;template('header');
$tmplContent = $templum-&gt;template('todo/list');
$tmplFooter = $templum-&gt;template('footer');

echo($tmplHeader-&gt;render() . $tmplContent-&gt;render() . $tmplFooter-&gt;render());

?&gt;</tt></pre>
</div></div>
<div class="para"><p>The example above defines three variables: <tt>$appTitle</tt>, <tt>$username</tt> and
<tt>$uiElements</tt>. It creates a new Templum instance, and immediately passes
<tt>$appTitle</tt> as a universal variable (using the <tt>compact()</tt> method). It then
sets two more universal variables <tt>$username</tt> and <tt>$uiElements</tt>. All three of
these variables are now available in every template you retrieve using the
Templum instance <tt>$templum</tt>.</p></div>
<div class="para"><p>You can set additional Universal variables using the <tt>Templum&#8594;setVar()</tt>
method of the Templum class. The <tt>setVar()</tt> method takes two parameters:
<tt>$varName</tt> and <tt>$varValue</tt>. For example:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>$templum-&gt;setVar('email', 'j.johnson@example.com');</tt></pre>
</div></div>
<h4 id="_global_variables">2.3.2. Global Variables:</h4>
<div class="para"><p>Global variables are available to a single template, and any templates that are
included by that template.
The global variables are set using the <tt>$varsGlobal</tt> parameter when you ask the
Templum class for a template using <tt>Templum&#8594;template()</tt> method. Global
variables will be available to the retrieved template and any templates
included by that template. Example:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>$templum-&gt;template('account/info', array(''=&gt;'');</tt></pre>
</div></div>
<div class="para"><p>Additional global variables can be set using the
<tt>TemplumTemplate&#8594;setVar()</tt> method on templates.</p></div>
<h4 id="_local_variables">2.3.3. Local Variables</h4>
<div class="para"><p>The Local variables are set when rendering the template by specifying the
<tt>$varsLocal</tt> parameter to the <tt>TemplumTemplate&#8594;render()</tt> method. The Local
variables will only be available to the template being rendered.</p></div>
<div class="para"><p>An easy way to pass variables is the PHP <tt>compact()</tt> function. It takes a list
a variable names as strings, and then looks at the current scope and creates an
associative array with the variables:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>$firstname = 'John';
$lastname = 'Johnson';

var_dump(compact('firstname', 'lastname'));

// Output:
//
// array(2) {
//   ["firstname"]=&gt;
//   string(4) "John"
//   ["lastname"]=&gt;
//   string(7) "Johnson"
// }</tt></pre>
</div></div>
<div class="para"><p>Here's an example that sets Universal, Global and Local variables:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>&lt;?php

require_once('../../src/templum.php');

$app_title = "MyApp";
$username = "fboender";
$controllerCurrent = "users.list";
$controllerTarget = "users.edit";
$users = array(
        "jjohnson"  =&gt; "John Johnson",
        "ppeterson" =&gt; "Pete Peterson",
        "jdoe"      =&gt; "John Doe"
);

// Universal variable $app_title
$templum = new Templum('view', compact('app_title'));

// Univeral variable $username
$templum-&gt;setVar('username', $username);

// Global variable $controllerCurrent
$template = $templum-&gt;template('users.list', compact('controllerCurrent'));

// Global variable $controllerTarget
$template-&gt;setVar('controllerTarget', $controllerTarget);

// Local variable '$users'
print($template-&gt;render(compact('users')));</tt></pre>
</div></div>
<h3 id="_inheritance">2.4. Inheritance</h3><div style="clear:left"></div>
<div class="para"><p>Templum features a simple template inheritance scheme which allows a template
to inherit from a generic parent template. This works by defining blocks in the
parent template which can be overridden by a child template. The inheritance
makes it very easy to create a generic layout template which is then filled in
by various child templates. The child templates can themselves determine
whether they want to be embedded in the generic layout template, making it easy
to create multiple different layouts.</p></div>
<div class="para"><p>Here's an example. First we define a parent template with a generic layout and
two blocks: a subtitle and the contents:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>&lt;h1&gt;Title&lt;/h1&gt;
&lt;h2&gt;[: block subtitle :]Parent template[: endblock :]&lt;/h2&gt;

&lt;div id="contents"&gt;
[: block contents :]This is the parent contents.[: endblock :]
&lt;/div&gt;</tt></pre>
</div></div>
<div class="para"><p>Next we define a child template which inherits from the template called
<em>parent</em> and which then overrides the subtitle and contents blocks:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>[[ $this-&gt;inherit('parent'); ]]
[: block subtitle :]child template.[: endblock :]
[: block contents :]
This is the child contents.
[: endblock :]</tt></pre>
</div></div>
<div class="para"><p>Now when we render the child template, it will be wrapped in the parent
template instead:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>&lt;?php
require_once('templum.php');

$templum = new Templum('./views');
$tpl = $templum-&gt;template('child');
print($tpl-&gt;render());
?&gt;</tt></pre>
</div></div>
<div class="para"><p>The output of which is:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>&lt;h1&gt;Title&lt;/h1&gt;
&lt;h2&gt;child template.&lt;/h2&gt;

&lt;div id="contents"&gt;
        This is the child contents.
&lt;/div&gt;</tt></pre>
</div></div>
<div class="para"><p>With this we can be build a complete hierarchy of templates that inherit from
eachother, where the parent template is at the top of the hierarchy and the
child template is at the bottom. We can create a lower template called
<em>grandchild</em> which can inherit from the <em>child</em> template and override a block
in that template:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>[[ $this-&gt;inherit('child'); ]]
[: block contents :]
This is the grandchild contents.
[: endblock :]</tt></pre>
</div></div>
<div class="para"><p>When we modify the calling code to call the grandchild template, we get:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>&lt;h1&gt;Title&lt;/h1&gt;
&lt;h2&gt;child template.&lt;/h2&gt;

&lt;div id="contents"&gt;
        This is the grandchild contents.
&lt;/div&gt;</tt></pre>
</div></div>
<div class="para"><p>As you can see, a block is always filled in with the contents defined by the
lowest template in the hierarchy that defines that block.</p></div>
<h3 id="_including">2.5. Including</h3><div style="clear:left"></div>
<div class="para"><p>You can easily include other templates in the current template using the
<tt>$this&#8594;inc()</tt> method. Example:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>&lt;h1&gt;Title&lt;/h1&gt;

&lt;div id="menu"&gt;
        @ $this-&gt;inc('menu')
&lt;/div&gt;
&lt;div id="contents"&gt;
        Contents.
&lt;/div&gt;</tt></pre>
</div></div>
<div class="para"><p>The contents of <tt>menu.tpl</tt> will then be included.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>&lt;ul&gt;
        &lt;li&gt;File
                &lt;ul&gt;
                        &lt;li&gt;Open..&lt;/li&gt;
                        &lt;li&gt;Quit&lt;/li&gt;
                &lt;/ul&gt;
        &lt;/li&gt;
&lt;/ul&gt;</tt></pre>
</div></div>
<h3 id="_internationalisation_i18n">2.6. Internationalisation (I18N)</h3><div style="clear:left"></div>
<div class="para"><p>Templum provides internationalisation through the use of translated templates.
These are simply normal templates with the locale suffixed on the filename. For
example:</p></div>
<div class="ilist"><ul>
<li>
<p>
<tt>helloworld.tpl</tt>: Default template, perhaps symlinked to one of the translated versions.
</p>
</li>
<li>
<p>
<tt>helloworld.tpl.en_US</tt>: (US) English version of the template.
</p>
</li>
<li>
<p>
<tt>helloworld.tpl.nl_NL</tt>: Dutch version of the template.
</p>
</li>
</ul></div>
<div class="para"><p>By default Templum refers to the <tt>helloworld.tpl</tt> template. You can tell
Templum which translation it should use by specifying a locale when
instantiating Templum:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>$locale = 'nl_NL';
$templum = new Templum('views/', array(), $locale);
$tpl = $templum-&gt;template('hellworld');</tt></pre>
</div></div>
<div class="para"><p>The example above will retrieve the dutch translation of the template:
<tt>helloworld.tpl.nl_NL</tt>. If no translated template is available Templum will
fall back to the default template.</p></div>
<h3 id="_errors">2.7. Errors</h3><div style="clear:left"></div>
<h4 id="_php_v5">2.7.1. PHP v5</h4>
<div class="para"><p>The two classes <tt>Templum</tt> and <tt>TemplumTemplate</tt> both have their own Exception
class:</p></div>
<div class="vlist"><dl>
<dt>
<tt>TemplumError</tt>
</dt>
<dd>
<p>
  This exception is thrown by the Templum class when an error occurs
  such as non-existing templates, etc.
</p>
</dd>
<dt>
<tt>TemplumTemplateError</tt>
</dt>
<dd>
<p>
  This exception is thrown by the <tt>TemplumTemplate</tt> class when errors occur in
  rendering your template. This includes PHP errors such as uninitialized
  variables. These errors are intercepted by the <tt>TemplumTemplate</tt> class and
  then raised as <tt>TemplumTemplateError</tt> exceptions.
</p>
</dd>
</dl></div>
<div class="para"><p>Fatal errors that occur during template rendering cannot be intercepted by
Templum, and therefor show normal PHP errors.</p></div>
<div class="para"><p>Please see the API documentation for information on which methods throw which
exceptions.</p></div>
<h4 id="_php_v4">2.7.2. PHP v4</h4>
<div class="para"><p>The PHP v4 support for errors in Templum is rather limited. Everything is
simply handled as a terminal error, and your script will die.</p></div>
</div>
<h2 id="_security">3. Security</h2>
<div class="sectionbody">
<h3 id="_automatic_html_escaping">3.1. Automatic HTML escaping</h3><div style="clear:left"></div>
<div class="para"><p>Templum tries to enhance the security of your application by automatically
escaping HTML entities in output generated using the <tt>{{</tt> and <tt>}}</tt> syntax. You
can turn this feature off using the <tt>Templum&#8594;setAutoEscape(False)</tt> method on
the Templum instance. This will turn off escaping for all templates retrieved
using that Templum instance.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>$templum = new Templum('views/');
$templum-&gt;setAutoEscape(False);</tt></pre>
</div></div>
<div class="para"><p>You can also disable escaping per template by passing <tt>False</tt> to the
<tt>$autoEscape</tt> parameter of the <tt>Templum&#8594;template()</tt> method like so:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>$templum = new Templum('views/');
$tpl = $templum-&gt;template('accounts/list', array(), False);</tt></pre>
</div></div>
<h3 id="_eval">3.2. Eval</h3><div style="clear:left"></div>
<div class="para"><p>Although Templum uses the <tt>eval()</tt> PHP function, which is generally regarded as
an unsafe construct, Templum never evaluates contents that can be influenced
from outside the template as it exists on disk. It is therefor not possible for
a remote attacker to inject data which might be interpreted as code by Templum.
Templum merely translates special constructs such as <tt>{{</tt> and <tt>}}</tt> to PHP code
for printing the contents between those constructs. It is therefor just as safe
as a normal <tt>echo()</tt> of a variable.</p></div>
<div class="para"><p>Care must be taken when dealing with Cross-site scripting attacks though. If you turn off Templum's automatic HTML entities escaping, or use another method of echoing variables than using the <tt>{{</tt> and <tt>}}</tt> syntax, you run the risk of injecting specially crafted HTML or Javascript code into the resulting page. Always properly sanitize any output.</p></div>
</div>
<div id="footer">
<div id="footer-text">
Version 0.4.0<br />
Last updated 2009-10-19 23:15:19 CEST
</div>
</div>
</body>
</html>
